OpenCode — 开源 AI 编程 Agent

OpenCode 是由 Anomaly 开发的开源 AI 编程 Agent， 支持终端（TUI）、桌面应用、IDE 扩展三种使用形态。 GitHub 190K+ Stars，月活开发者 750 万+， 支持 75+ LLM 提供商及本地模型，是目前社区最活跃的 AI 编程工具之一。

1. 概述

OpenCode 是一个AI 编码代理（Coding Agent），能理解自然语言指令， 自主调用工具（读写文件、执行命令、搜索代码、获取网页等）来完成软件工程任务。 它不只是一个代码补全工具，而是一个能理解项目上下文、制定计划、执行多步操作的智能体。

核心特性

• LSP 集成 — 自动加载语言服务器，为 LLM 提供代码智能（跳转定义、引用查找等）
• 多会话并行 — 在同一项目中启动多个 Agent 并行工作
• 会话分享 — 生成可分享的会话链接，用于协作或调试
• GitHub Copilot 兼容 — 用 GitHub 账号登录即可使用 Copilot 配额
• ChatGPT Plus/Pro 兼容 — 用 OpenAI 账号登录即可使用订阅模型
• 75+ 提供商 — 通过 Models.dev 支持任意 LLM 提供商，包括本地模型
• 多种界面 — 终端界面（TUI）、桌面应用、IDE 扩展（VS Code 等）
• 隐私优先 — 不存储任何代码或上下文数据

AI Agent 能力边界

• 能做的：读/写/编辑文件、执行 bash 命令、搜索代码、获取网页、管理 TODO、加载 Skills、启动子 Agent
• 受控的：通过权限系统（permission）精细控制每个工具的执行策略（allow/ask/deny）
• 不能做的：无法突破权限限制、无法访问被 deny 的外部目录、无法绕过企业策略

OpenCode 这类工具叫什么

OpenCode 这类工具在业界通常被称为 AI Agent（AI 智能体）， 更精确地说是 AI 编程 Agent（AI Coding Agent / 编程代理）。 它与普通 Chatbot 的本质区别在于能自主完成任务—— 读代码、执行命令、改文件、验证结果，而不只是做单轮问答（那种只叫 Chatbot/Assistant）。

Harness Engineering（驾驭工程）

Harness（缰绳/驾驭）工程指在构建 AI Agent 时， 把模型自由度较大的输出"驾驭"到一个安全、可控、可审计、可终止的交互框架里的工程实践。 模型本身能力不稳定，不能让它随意执行，因此需要设计一层约束，让 Agent 的行为可预测、可控、可终止。

Harness 层典型内容：

• 工具调用约束 — 只允许调用白名单工具，参数必须符合 schema（如 OpenCode 的 Bash/Edit/Write）
• 权限与批准机制 — 危险操作需用户确认（permission rules）
• 循环控制 — 限制最大步数、超时、防死循环（如 OpenCode 的 maxSteps）
• 沙箱/隔离 — 命令在受限环境执行，防止模型失控
• 状态持久化 — 会话管理，跨步骤保持上下文
• 错误恢复 — 工具失败时引导模型重新规划

1.1 CLI 前端技术栈

OpenCode 的终端界面（TUI）基于自研框架 OpenTUI，使用 SolidJS 作为响应式 UI 层，直接渲染到终端。

2. 行为分析（做什么）

以下从行为视角分析 OpenCode 的功能边界与运行流程。

2.1 用例图 — 用户与 OpenCode 的交互全景

展示三类主要参与者与 OpenCode 系统的功能交互边界。

图 1：OpenCode 顶层用例图

2.2 活动图 — 一次典型 Session 的执行流程

展示从用户输入到代码变更的完整活动链，覆盖 Plan 模式与 Build 模式的分支。

图 2：OpenCode Session 执行活动图（带泳道）

2.3 序列图 — System Prompt 组装与 ReAct 循环（以 DeepSeek V4 Pro 为例）

以 DeepSeek V4 Pro 为例（模型 ID 不命中 claude/gpt/gemini/kimi/trinity 等关键词，兜底使用 default.txt）。该 Prompt 中无显式 ReAct 自动继续指令，循环全由代码层驱动。序列图分两阶段：System Prompt 组装 + ReAct 循环的完整退出决策链。

图 3：以 DeepSeek V4 Pro 为例 — System Prompt 组装 → ReAct 循环（含 7 个退出判定点）

ReAct 循环退出条件总览（prompt.ts:1088 while(true)）

OpenCode 的 ReAct 循环不只依赖 LLM 有无 tool_call 一个条件来判定是否终止，完整的退出决策包含 7 个判定条件，分布在循环体头部、尾部和 Processor 内部：

3. 结构分析（由什么组成）

以下从结构视角分析 OpenCode 的组件架构与核心抽象。

3.1 组件图 — 系统宏观架构

展示 OpenCode 的分层组件架构及组件间的依赖关系。

图 4：OpenCode 系统组件架构图

3.2 概念类图 — 核心抽象与关系

展示 OpenCode 中关键概念实体及其关系，不涉及具体实现细节。

图 5：OpenCode 核心概念类图

4. 配置示例与 Demo

4.1 基础配置（opencode.json）

项目级配置，设置模型、权限、自动更新等。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "share": "manual",
  "snapshot": true,
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"],
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny"
    }
  },
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  },
  "disabled_providers": ["openai"],
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

4.2 自定义 Agent

JSON 方式：

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "steps": 10,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Markdown 方式（.opencode/agents/docs-writer.md）：

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---
You are a technical writer. Create clear, comprehensive documentation.
Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

4.3 自定义 Skill

在 .opencode/skills/git-release/SKILL.md 中定义可复用技能：

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

4.4 自定义 Command

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report.\nShow any failures and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript.",
      "description": "Create a new component"
    }
  }
}

5. 实战速查手册

5.1 CLI 命令速查

5.2 内置工具速查

5.3 内置 Agent 速查

5.4 配置键速查

配置加载优先级

1. Remote config — .well-known/opencode（组织默认）
2. Global config — ~/.config/opencode/opencode.json（用户偏好）
3. Custom config — OPENCODE_CONFIG 环境变量
4. Project config — 项目根 opencode.json
5. .opencode 目录 — agents、commands、plugins、skills
6. Inline config — OPENCODE_CONFIG_CONTENT 环境变量
7. Managed config — 系统管理路径（macOS/Linux/Windows）
8. macOS MDM — .mobileconfig 托管（最高优先级）

权限模型速查

权限键支持通配符匹配，最后匹配规则生效。典型模式：

{
  "permission": {
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "rm *": "deny"
    }
  }
}

TUI 常用按键

6. Agent System Prompt 深度梳理

以下从 ReAct 范式 出发，梳理 OpenCode 如何通过 Prompt 设计实现 Reasoning + Acting 的自主循环。源码路径：packages/opencode/src/session/prompt/、packages/opencode/src/agent/prompt/、packages/core/src/session/runner/。

6.1 ReAct 循环总览

图 6：OpenCode ReAct 推理-行动循环（V1 路径，prompt.ts:1081-1338）

V1 循环（packages/opencode/src/session/prompt.ts:1081-1338 runLoop()）和 V2 循环（packages/core/src/session/runner/llm.ts:378-401）共享同一核心模式：

1. LLM 推理 → 产生文本或工具调用（tool_call）
2. 权限检查 → allow/ask/deny
3. 执行工具 → 产生输出（tool_result）
4. 工具结果发送回 LLM → LLM 观察结果，决定下一步
5. 继续循环 → 直到 LLM 输出纯文本（无工具调用），或到达 maxSteps 上限

6.2 Prompt 中驱动 ReAct 循环的关键文本

不同模型版本的系统提示词中，编码了不同强度的 ReAct 循环指令。以下是各模型版本中明确驱回 ReAct 行为的原文：

6.3 消息结构：ReAct 循环的物质基础

ReAct 循环之所以能运行，核心在于 工具调用/结果的往返消息格式。每一次 ReAct 循环步（step）在协议层就是一组消息：

┌─────────────────────────────────────────────┐
│ Step N:   assistant(tool_call: read "foo.ts")│  ← LLM 推理出"需要读文件" → 行动
│            ↓                                 │
│           tool_result("foo.ts" 的内容)        │  ← 工具执行完毕 → 观察
│            ↓                                 │
│ Step N+1: assistant(tool_call: edit "foo.ts")│  ← LLM 根据结果决定下一步 → 再行动
│            ↓                                 │
│           tool_result("edit OK")              │
│            ↓                                 │
│ Step N+2: assistant(text: "修改完成")         │  ← LLM 判断任务完成 → 输出纯文本 → 循环结束
└─────────────────────────────────────────────┘

消息转换源码：

6.4 ReAct 循环的工程约束

6.4.1 Max Steps 上限

循环不是无限的。每个 Agent 有 steps 配置（默认 Infinity），当到达上限时注入 MAX_STEPS_PROMPT：

CRITICAL - MAXIMUM STEPS REACHED

The maximum number of steps allowed for this task has been reached. Tools are
disabled until next user input. Respond with text only.

STRICT REQUIREMENTS:
1. Do NOT make any tool calls
2. MUST provide a text response summarizing work done so far
3. This constraint overrides ALL other instructions

Response must include:
- Statement that maximum steps have been reached
- Summary of what has been accomplished
- List of any remaining tasks not completed
- Recommendations for next steps

6.4.2 Doom Loop 检测

packages/opencode/src/session/processor.ts:354-377 — 如果同一 assistant 消息的最后 3 次工具调用（DOOM_LOOP_THRESHOLD = 3）是相同工具+相同参数，触发 doom_loop 权限请求，阻止 LLM 陷入死循环。

6.4.3 续跑提示

过程中多处注入提示促使 LLM 继续循环：

6.5 Prompt 组装流程

图 7：OpenCode System Prompt 组装流程

组装公式（V1 路径）：

// 1. 选择基础 System Prompt（根据 model ID）
system = agent.customPrompt || model-base.txt

// 2. 拼接用户自定义 system（来自 opencode.json config 的 system 字段）
system += user.system

// 3. 拼接环境上下文
system += env_info  // model, workspace, git status, platform, date

// 4. 拼接指令文件
system += AGENTS.md / CLAUDE.md / project instructions

// 5. 拼接工具上下文
system += MCP tools + available skills list

关键源码位置：

6.6 模型专属 System Prompt 汇总

位于 packages/opencode/src/session/prompt/*.txt，由 SystemPrompt.provider(model) 选择。

6.7 子 Agent 专用 Prompt

子 Agent 启动时用自己的 System Prompt 替换主 Agent 的模型专属 Prompt。位于 packages/opencode/src/agent/prompt/*.txt，packages/core/src/plugin/agent.ts 中有等价 TypeScript 常量。

6.8 system-reminder 运行时注入

运行时动态注入到用户消息中的 <system-reminder> 块，由 SessionReminders.apply()（packages/opencode/src/session/reminders.ts）根据 Agent 模式和会话状态插入。

此外，Prompt 中明确告诉 LLM 如何解读这些标签——不同模型版本措辞强度不同：

6.9 请求体分析：为什么一句"你好"消耗 9k token？

6.9.1 SQLite 数据库中的 token 记录

每次 LLM 请求的 token 用量持久化在 ~/.local/share/opencode/opencode.db 的 message 表中。以一条 "find opencode.html" 消息为例：

sqlite3 ~/.local/share/opencode/opencode.db "
SELECT json_extract(data, '$.tokens.total')   as total,
       json_extract(data, '$.tokens.input')   as input,
       json_extract(data, '$.tokens.cache.read') as cache_read,
       json_extract(data, '$.tokens.output')  as output,
       json_extract(data, '$.tokens.reasoning') as reasoning
FROM message WHERE json_extract(data, '$.role') = 'assistant'
ORDER BY time_created LIMIT 1;
"

-- 结果: total=9063  input=18  cache_read=8960  output=66  reasoning=19

6.9.2 请求体组成与 token 构成

完整请求体由 6 条 system message + 用户消息 + 11 个 tool schema 组成：

  cache_read 9600 tokens 构成:

     default.txt       ████████████████░░░░░  1300  (14.5%)
     风格指令+示例        ██████████████████████████████████████░░  3060  (34.1%)
     工具 JSON Schema    ███████████████████████████████████████  3100  (34.6%)
     技能定义            ██████████████░░  1200  (13.4%)
     AGENTS.md          ██░  200  (2.2%)
     环境信息            █░  100  (1.1%)

6.9.3 请求组装流程（源码级）

每次 LLM 调用的请求体在 llm/request.ts 的 LLMRequestPrep.prepare() 中内存组装，组装完直接传给 streamText()，中间无任何日志或持久化：

// prompt.ts:1257-1286 — 每个 loop 迭代组装 system + messages + tools
const [skills, env, instructions, mcpInstructions, modelMsgs] =
  yield* Effect.all([
    sys.skills(agent),                         // 技能描述
    sys.environment(model),                    // 环境信息 + AGENTS.md 内容
    instruction.system().pipe(Effect.orDie),   // AGENTS.md 路径
    sys.mcp(agent, session.permission),        // MCP 指令（如有）
    MessageV2.toModelMessagesEffect(msgs, model), // 对话历史
  ])

const system = [...env, ...instructions, ...(mcpInstructions ? [mcpInstructions] : []), ...(skills ? [skills] : [])]

// llm/request.ts:104 — 拼接 final messages
const messages = [
  ...system.map((x) => ({ role: "system", content: x })),
  ...input.messages,
]

// 然后直接 streamText({ messages, tools, ... }) → HTTP POST 到 API

6.9.4 真正能看到请求体的方法

6.9.5 源码级追踪

对于 DeepSeek 等非 GPT/Claude/Gemini 模型，使用的默认 system prompt：

6.9.6 还原演示：完整请求体 JSON

根据源码 + AGENTS.md + 技能列表 + 工具 schema 还原的"你好"请求体（下载 JSON）：

{
  "model": "deepseek/deepseek-v4-pro",
  "temperature": 0.3,
  "messages": [
    {
      "role": "system",
      "content": "You are opencode, an interactive CLI tool that helps users with software engineering tasks..."
    },
    {
      "role": "system",
      "content": "You are powered by the model named deepseek-v4-pro...\n<env>\n  Working directory: /Users/brian/microarch\n  Platform: darwin\n</env>\nInstructions from: /Users/brian/.config/opencode/AGENTS.md\n# AGENTS\n## Microarch 公司结构\n..."
    },
    {
      "role": "system",
      "content": "Skills provide specialized instructions...\n<available_skills>\n  <skill><name>find-file</name>...</skill>\n  <skill><name>fix-uml</name>...</skill>\n  <skill><name>local-ocr</name>...</skill>\n  <skill><name>opencloudos-restart-bot</name>...</skill>\n  <skill><name>pull-all</name>...</skill>\n  <skill><name>push-all</name>...</skill>\n  <skill><name>send-email</name>...</skill>\n  <skill><name>teardown</name>...</skill>\n  <skill><name>ubuntu-restart-bot</name>...</skill>\n  <skill><name>customize-opencode</name>...</skill>\n</available_skills>"
    },
    {
      "role": "system",
      "content": "## Tools\n\nYou have access to a set of tools to help answer the user's questions..."
    },
    {
      "role": "user",
      "content": "你好"
    }
  ],
  "tools": [
    { "type": "function", "function": { "name": "bash",       "description": "Executes a given bash command...",              "parameters": { "type":"object", "properties":{ "command":{},"workdir":{},"timeout":{} }, "required":["command"] } } },
    { "type": "function", "function": { "name": "edit",       "description": "Performs exact string replacements...",          "parameters": { "type":"object", "properties":{ "filePath":{},"oldString":{},"newString":{},"replaceAll":{} }, "required":["filePath","oldString","newString"] } } },
    { "type": "function", "function": { "name": "glob",       "description": "Fast file pattern matching tool...",              "parameters": { "type":"object", "properties":{ "pattern":{},"path":{} }, "required":["pattern"] } } },
    { "type": "function", "function": { "name": "grep",       "description": "Fast content search tool...",                    "parameters": { "type":"object", "properties":{ "pattern":{},"path":{},"include":{} }, "required":["pattern"] } } },
    { "type": "function", "function": { "name": "question",   "description": "Use this tool when you need to ask the user...", "parameters": { "type":"object", "properties":{ "questions":{} }, "required":["questions"] } } },
    { "type": "function", "function": { "name": "read",       "description": "Read a file or directory...",                    "parameters": { "type":"object", "properties":{ "filePath":{},"offset":{},"limit":{} }, "required":["filePath"] } } },
    { "type": "function", "function": { "name": "skill",      "description": "Load a specialized skill...",                    "parameters": { "type":"object", "properties":{ "name":{} }, "required":["name"] } } },
    { "type": "function", "function": { "name": "task",       "description": "Launch a new agent...",                           "parameters": { "type":"object", "properties":{ "description":{},"prompt":{},"subagent_type":{} }, "required":["description","prompt","subagent_type"] } } },
    { "type": "function", "function": { "name": "todowrite",  "description": "Create and maintain a structured task list...",  "parameters": { "type":"object", "properties":{ "todos":{} }, "required":["todos"] } } },
    { "type": "function", "function": { "name": "webfetch",   "description": "Fetches content from a specified URL...",        "parameters": { "type":"object", "properties":{ "url":{} }, "required":["url"] } } },
    { "type": "function", "function": { "name": "write",      "description": "Writes a file to the local filesystem...",       "parameters": { "type":"object", "properties":{ "content":{},"filePath":{} }, "required":["content","filePath"] } } }
  ],
  "total_estimated_tokens": 9063,
  "token_breakdown": {
    "cache_read": 8960,
    "input": 18,
    "output": 66,
    "reasoning": 19
  },
  "cache_read_breakdown": {
    "default_txt_system_prompt": "~1300 tokens",
    "AGENTS_md": "~200 tokens",
    "environment_info": "~100 tokens",
    "skills_definitions": "~1200 tokens",
    "tool_definitions_schemas": "~3100 tokens",
    "other_system_instructions": "~3060 tokens"
  }
}

注：工具 schema 中每个 parameters.properties 仅保留了 key，省略了 type/description 以节省篇幅。真实请求中的 tool schema 更冗长（含完整的 JSON Schema description），占 cache_read 的大头（~34.6%）。